feat(objectql): ValidationError publishes its error code as a constant — the last row of #16159 - #16443

Closes #16159

ValidationError publishes its ADR-0112 code as an importable constant. This is the eleventh and last row of #16159's census, on the shape the four landed slices set (#16156, #16259, #16283, #16308, #16326): an exported X_CODE = 'LITERAL' as const, the class field reading it as a bare readonly code = X_CODE;, a barrel re-export, and a pin test.

All readings below were taken on this branch at fc1e76583, in a dedicated worktree cut from origin/main ac76425f0.

Why Closes and not Part of — the census, re-run rather than inherited

The card's table has 11 rows and this PR takes the last one. The count was re-derived with the card's own definition (a class extending Error that carries a code), not by trusting the table:

Other spellings were checked rather than assumed, because readonly code = is only one of them: this.code = returns 0 in non-test packages/objectql/src; readonly code: returns 1, the interface above; a bare code = class field returns 0; a class extending any error base other than Error returns 0. So there is no twelfth row hiding under a different spelling, and this PR discharges the card.

The wire string did not change

The quoted literal 'VALIDATION_FAILED' occurs exactly once in executable position on both sides of the diff — at base as the class field, at head as the constant's value. It moved; it did not multiply and it did not mutate. (The other occurrences in that file are prose inside docblocks, at base and at head alike.)

It does not answer the question the card fenced off

secret-fields.ts publishes EMPTY_CREDENTIAL_REFUSAL_CODE = 'VALIDATION_ERROR' while this site spells 'VALIDATION_FAILED', and the card says in its own words that "whether they should converge is a question this card does not answer". Publishing the current spelling leaves that decision exactly as open as it was — a convergence is a breaking rename of a registered wire code either way — and a pin test asserts the two are still two, so a future ruling has to argue for itself rather than arrive as a side effect. That open question is filed as #16440, because the card carrying the note is the one this PR discharges. #16440 stays open and is out of scope here.

Clause-② — yes, measured

Ablation over every declaration file files[] publishes (files is ['dist','README.md','CHANGELOG.md'], so all six .d.ts/.d.mts count, not just the two entry points), comparing exported NAME SETS rather than bytes, because a byte diff here is dominated by tsup's internal alias renumbering and the content-hashed chunk filename, neither of which is a surface change:

Additive widening, limb 1, nothing removed ⇒ Clause-②: yes and a minor changeset. No **BREAKING** banner is owed: that is the limb-2 narrowing shape, and this narrows nothing.

The member-level reading, which the name set is blind to by construction, and it did move: the emitted class member goes from readonly code = "VALIDATION_FAILED"; to readonly code: "VALIDATION_FAILED";. That is an emit-form change with no type change — proved with a standalone tsc --strict probe that asserts bidirectional assignability between the two forms and carries a firing negative control (a different literal is refused, so the member is not silently string). It is also the emit form every landed sibling already ships: DriverConnectError reads readonly code: "ERR_DRIVER_CONNECT"; in today's dist.

Byte-diff hunks, classified rather than counted: index.d.ts is 2939 lines on both legs and differs on exactly two — line 1 (the content-hashed chunk filename) and line 2 (the export list, gaining b2 as VALIDATION_FAILED_CODE and renumbering the aliases after it). core.d.ts differs only by that filename, which is why its name set is unmoved.

Ablation hygiene: the mutation was proven on disk (git hash-object equal to the base blob and different from the HEAD blob, both files, plus a zero-count anchor on VALIDATION_FAILED_CODE); the rebuild was proven rather than assumed (dist/index.d.ts mtime 1788743496 ⇒ 1788743598, chunk util-Dw5ZTIII ⇒ util-CTOUTmfv); the restore is byte-exact (git diff HEAD empty, both blobs equal to their HEAD blobs) and the restore-leg rebuild reproduced the head dist sha-for-sha, so no mutated artifact survived into any later measurement.

The docblock-ordering trap, proved in the emitted output

Two consecutive top-level JSDoc blocks both attach to the declaration that follows, which is what stranded three class docblocks in #16308. The constant and its docblock therefore sit above the class. Verified in the built dist/util-Dw5ZTIII.d.ts with the package's own tsup and no turbo cache on the path: the docblock lands on declare const VALIDATION_FAILED_CODE, and declare class ValidationError follows carrying exactly the documentation it had at base — which is none, since this class has never had a docblock of its own. Nothing was stranded and nothing was invented.

The two gates are inverted, and this row lands on the provenance side

VALIDATION_FAILED is registered in ERROR_CODE_LEDGER under @objectstack/objectql (packages/spec/src/api/error-code-ledger.zod.ts, the last entry of that owner's block), so:

• check:error-code-provenance is non-neutral and moved by exactly one: 317 ⇒ 318 stamp sites, 301 ⇒ 302 listed, waivers unchanged at 16, exit 0 on both legs. It accepts the new constdef site because the code is listed under this package's own owner key.
• check:dispatcher-error-vocabulary is neutral by construction: that table records UNREGISTERED sites, so a registered code is invisible to it. VALIDATION_FAILED returns 0 in packages/runtime/src/dispatcher-error-vocabulary.ts against a firing control of DUPLICATE_ARTIFACT_OBJECT_NAME = 2 in the same file. The gate reads OK — 66 unregistered code-stamping site(s), all classified, unchanged. No cross-package edit is owed.

Consumer-side census — measured, and nothing outside packages/objectql is rewired

'VALIDATION_FAILED' is re-authored as an inline literal at 148 non-test sites across 33 files. The headline number is not the interesting part; the classification is, and it cuts the other way from what a raw count suggests:

• Independent producers, not consumers — the large majority. @objectstack/rest's own response bodies and its VALIDATION_FAILED: … message-prefix convention (31 sites in rest-server.ts alone), plugin-approvals' identical message-prefix convention (26 sites, plus one site that consumes its own prefix), plugin-sharing's SharingCriteriaValidationError — declared locally on purpose, its docblock saying "so a security guard in a plugin never depends on another package's build output at runtime" — and @objectstack/metadata-protocol's own class, whose docblock calls the code "this package's own house code". Folding any of these in would be a cross-package coupling this card never asked for.
• Genuine recognizers of this class — four, and these are the sites the export exists for: packages/types/src/validation-failure.ts and packages/rest/src/error-response.ts each test code === 'VALIDATION_FAILED' || name === 'ValidationError', error-response.ts tests the wire body's code a second time, and packages/plugins/plugin-auth/src/objectql-adapter.ts does the same to map an engine refusal onto a better-auth APIError. Each holds its own copy of the string today.
• packages/client/src/index.ts is prose only: all seven occurrences are JSDoc and comments, including the documented branch if (err.code === 'VALIDATION_FAILED'), and the client reads the HTTP envelope rather than this class.

No consumer is rewired here. The card's scope is the producer-side importable constant.

./core asymmetry, recorded not decided

ValidationError is published from the lean ./core entry as well as the batteries barrel; its constant, like every existing *_CODE in this package, goes on the barrel only (core.ts contains zero _CODE exports, and dist/core.d.ts's name set is 79 on both legs). That is batch-i's ruling A, applied unchanged, and it adds one more instance to the population #16260 owns — a question this PR deliberately leaves where it is. #16260 remains open and is not addressed here.

Verification

Gate results are quoted from each gate's own verdict line; every exit code was captured by redirect-then-read, never through a pipe.

• Tests — pnpm --filter @objectstack/objectql exec vitest run --maxWorkers=2 over the 19 objectql test files naming ValidationError or VALIDATION_FAILED: Test Files 19 passed (19), Tests 503 passed (503), exit 0. Declared narrowing: the package has far more test files; CI runs the farm.
• Typecheck — pnpm --filter @objectstack/objectql typecheck exit 0, ratchet held at 44 file(s) / 242 error(s) / 69 pinned signature(s). Not a bare exit 0: inclusion was proved with tsc --listFiles. The main program is 545 files and contains record-validator.ts and index.ts but not the new test file (so its green says nothing about the test); the tsconfig.test.json program is 1185 files and contains all three, including the new pin test. Absent-file control: 0 hits in both.
• Repo-wide lint — pnpm lint (eslint . --no-inline-config) exit 0, run whole. No narrowing claimed.
• Gate families — derived from the diff with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (script blob verified identical to origin/main's, so not a stale checker; it reports 58 runnable families). Run locally and green: check:nul-bytes (scanned 8080 text file(s) … no raw ASCII control bytes), check:error-code-casing, check:dispatcher-error-vocabulary, check:error-code-provenance, check:system-context-census (105 elevation read sites … all anchored), check:doc-authoring, check:published-files, check:engine-double-contract, check:where-matcher, check:objectql-double-limit, check:test-source-alias, check:type-source-resolution, check:cross-package-test-inputs, check:error-status-conformance, check:type-check-coverage, check:objectui-changeset, check:changeset-gate-self-tests, check:dts-closure (population checked, not quoted blind: 15 built package(s) swept, objectql among them), check-changeset-no-major, check-adr-0087-registration, check-empty-changeset, check-changeset-fixed.
• Line-number anchor family — a diff that changes a file's line count can falsify a path:NNN anchor even when it moves nothing else. check:system-context-census is green; independently, 0 path:NNN anchors reference either edited file from outside packages/objectql/src, against a firing control of 14 hits for registry.ts/engine.ts on the identical grep shape. Repo-wide there are 11 prose references of the form record-validator.ts:NNN, and every one of them was already stale on origin/main before this diff — checked line by line: the text cited at :471, verbatim free-form (tags without options), lives at :790 on origin/main, and allowed.length > 0 cited at :205/:212 lives at :772. This diff shifts already-wrong anchors; it falsifies none that were true. Filed as [finding] a pinned NON-rule in packages/spec justifies itself with a record-validator.ts line number that is 319 lines off, and nothing checks prose line anchors #16441 rather than repaired here — that card is out of scope for this PR and remains open.
• NOT MEASURED, stated so it is not mistaken for a pass — check:dual-build-cjs-loads exits 3 with Run pnpm build first. This is NOT a pass: nothing was measured, because 47 sibling packages have no dist in this worktree; it is CI's Build Core job that has the built closure. check:single-claim-paths exits 2 with NOT WIRED — PR_NUMBER is not set … This is a wiring or usage failure, NOT a verdict; it is re-run against this PR number below. check-changeset-no-major's LEVEL AXIS reports NOT MEASURED locally for the same reason — no pull_request payload — and its no major bump limb is green.

Generated by Claude Code